TypeScript Yapılandırması: TSConfig Derleyici Seçeneklerinde Uzmanlaşmak

tsconfig.json dosyası, herhangi bir TypeScript projesinin kalbidir. TypeScript derleyicisinin (tsc) .ts dosyalarınızı JavaScript'e nasıl dönüştüreceğini belirler. İyi yapılandırılmış bir tsconfig.json, kod kalitesini korumak, farklı ortamlarda uyumluluğu sağlamak ve derleme sürecini optimize etmek için çok önemlidir. Bu kapsamlı rehber, gelişmiş tsconfig.json seçeneklerine derinlemesine dalmakta ve TypeScript projelerinizi en yüksek performans ve sürdürülebilirlik için ince ayar yapmanızı sağlamaktadır.

Temelleri Anlamak: TSConfig Neden Önemlidir?

Gelişmiş seçeneklere geçmeden önce, tsconfig.json'un neden bu kadar önemli olduğunu özetleyelim:

• Derleme Kontrolü: Projenize hangi dosyaların dahil edilmesi gerektiğini ve bunların nasıl derlenmesi gerektiğini belirtir.
• Tip Kontrolü: Tip kontrolünün kurallarını ve titizliğini tanımlayarak, geliştirme döngüsünün başlarında hataları yakalamanıza yardımcı olur.
• Çıktı Kontrolü: Hedef JavaScript sürümünü, modül sistemini ve çıktı dizinini belirler.
• IDE Entegrasyonu: Kod tamamlama, hata vurgulama ve yeniden düzenleme gibi özellikler için IDE'lere (VS Code, WebStorm vb. gibi) değerli bilgiler sağlar.

Bir tsconfig.json dosyası olmadan, TypeScript derleyicisi, tüm projeler için uygun olmayabilecek varsayılan ayarları kullanacaktır. Bu, beklenmedik davranışlara, uyumluluk sorunlarına ve idealden daha az bir geliştirme deneyimine yol açabilir.

TSConfig'unuzu Oluşturma: Hızlı Başlangıç

Bir tsconfig.json dosyası oluşturmak için, projenizin kök dizininde aşağıdaki komutu çalıştırmanız yeterlidir:

            tsc --init
            

              
                Copy
              
            
          

Bu, bazı yaygın seçeneklerle temel bir tsconfig.json dosyası oluşturacaktır. Daha sonra bu dosyayı projenizin özel gereksinimlerini karşılayacak şekilde özelleştirebilirsiniz.

Temel Derleyici Seçenekleri: Ayrıntılı Bir Bakış

tsconfig.json dosyası, TypeScript derleyicisini yapılandırdığınız compilerOptions nesnesini içerir. En önemli ve yaygın olarak kullanılan seçeneklerden bazılarını inceleyelim:

target

Bu seçenek, derlenen JavaScript kodu için ECMAScript hedef sürümünü belirtir. Derleyicinin kullanacağı JavaScript özelliklerini belirleyerek, hedef ortamla (örneğin, tarayıcılar, Node.js) uyumluluğu sağlar. Yaygın değerler arasında ES5, ES6 (ES2015), ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext bulunur. ESNext kullanmak, en son desteklenen ECMAScript özelliklerini hedefleyecektir.

Örnek:

            "compilerOptions": {
  "target": "ES2020"
}
            

              
                Copy
              
            
          

Bu yapılandırma, derleyiciye ECMAScript 2020 ile uyumlu JavaScript kodu oluşturmasını emredecektir.

module

Bu seçenek, derlenen JavaScript kodunda kullanılacak modül sistemini belirtir. Yaygın değerler arasında CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ve ESNext bulunur. Modül sistemi seçimi, hedef ortama ve kullanılan modül yükleyiciye (örneğin, Node.js, Webpack, Browserify) bağlıdır.

Örnek:

            "compilerOptions": {
  "module": "CommonJS"
}
            

              
                Copy
              
            
          

Bu yapılandırma, genellikle CommonJS modül sistemini kullanan Node.js projeleri için uygundur.

lib

Bu seçenek, derleme işlemine dahil edilecek kitaplık dosyası kümesini belirtir. Bu kitaplık dosyaları, yerleşik JavaScript API'leri ve tarayıcı API'leri için tür tanımlamaları sağlar. Yaygın değerler arasında ES5, ES6, ES7, DOM, WebWorker, ScriptHost ve daha fazlası bulunur.

Örnek:

            "compilerOptions": {
  "lib": ["ES2020", "DOM"]
}
            

              
                Copy
              
            
          

Bu yapılandırma, ECMAScript 2020 ve DOM API'si için tür tanımlamalarını içerir, bu da tarayıcı tabanlı projeler için gereklidir.

allowJs

Bu seçenek, TypeScript derleyicisinin TypeScript dosyalarıyla birlikte JavaScript dosyalarını derlemesine izin verir. Bu, bir JavaScript projesini TypeScript'e geçirirken veya mevcut JavaScript kod tabanlarıyla çalışırken kullanışlı olabilir.

Örnek:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

Bu seçenek etkinleştirildiğinde, derleyici hem .ts hem de .js dosyalarını işleyecektir.

checkJs

Bu seçenek, JavaScript dosyaları için tip kontrolünü etkinleştirir. allowJs ile birleştirildiğinde, TypeScript'in JavaScript kodunuzdaki potansiyel tip hatalarını belirlemesini sağlar.

Örnek:

            "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}
            

              
                Copy
              
            
          

Bu yapılandırma, hem TypeScript hem de JavaScript dosyaları için tip kontrolü sağlar.

jsx

Bu seçenek, JSX sözdiziminin (React ve diğer çerçevelerde kullanılır) nasıl dönüştürülmesi gerektiğini belirtir. Yaygın değerler arasında preserve, react, react-native ve react-jsx bulunur. preserve JSX sözdizimini olduğu gibi bırakır, react onu React.createElement çağrılarına dönüştürür, react-native React Native geliştirmesi içindir ve react-jsx onu JSX fabrika fonksiyonlarına dönüştürür. react-jsxdev geliştirme amaçlıdır.

Örnek:

            "compilerOptions": {
  "jsx": "react"
}
            

              
                Copy
              
            
          

Bu yapılandırma, JSX'i React.createElement çağrılarına dönüştüren React projeleri için uygundur.

declaration

Bu seçenek, TypeScript kodunuz için bildirim dosyaları (.d.ts) oluşturur. Bildirim dosyaları, kodunuz için tür bilgisi sağlar ve diğer TypeScript projelerinin veya JavaScript projelerinin, kodunuzu uygun tip kontrolü ile kullanmasına izin verir.

Örnek:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

Bu yapılandırma, derlenen JavaScript dosyalarıyla birlikte .d.ts dosyaları oluşturacaktır.

declarationMap

Bu seçenek, oluşturulan bildirim dosyaları için kaynak harita dosyaları (.d.ts.map) oluşturur. Kaynak haritalar, hata ayıklayıcıların ve diğer araçların, bildirim dosyalarıyla çalışırken orijinal TypeScript kaynak koduna geri eşlenmesini sağlar.

Örnek:

            "compilerOptions": {
  "declaration": true,
  "declarationMap": true
}
            

              
                Copy
              
            
          

sourceMap

Bu seçenek, derlenen JavaScript kodu için kaynak harita dosyaları (.js.map) oluşturur. Kaynak haritalar, hata ayıklayıcıların ve diğer araçların, tarayıcıda veya diğer ortamlarda hata ayıklama yaparken orijinal TypeScript kaynak koduna geri eşlenmesini sağlar.

Örnek:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

Bu seçenek, tüm çıktı dosyalarını tek bir dosyada birleştirir ve yayar. Bu genellikle tarayıcı tabanlı uygulamalar için kodu paketlemek için kullanılır.

Örnek:

            "compilerOptions": {
  "outFile": "dist/bundle.js"
}
            

              
                Copy
              
            
          

outDir

Bu seçenek, derlenen JavaScript dosyaları için çıktı dizinini belirtir. Belirtilmezse, derleyici çıktı dosyalarını kaynak dosyalarla aynı dizine yerleştirir.

Örnek:

            "compilerOptions": {
  "outDir": "dist"
}
            

              
                Copy
              
            
          

Bu yapılandırma, derlenen JavaScript dosyalarını dist dizinine yerleştirecektir.

rootDir

Bu seçenek, TypeScript projesinin kök dizinini belirtir. Derleyici, modül adlarını çözümlemek ve çıktı dosya yollarını oluşturmak için bu dizini kullanır. Bu, özellikle karmaşık proje yapıları için kullanışlıdır.

Örnek:

            "compilerOptions": {
  "rootDir": "src"
}
            

              
                Copy
              
            
          

removeComments

Bu seçenek, derlenen JavaScript kodundan yorumları kaldırır. Bu, çıktı dosyalarının boyutunu küçültmeye yardımcı olabilir.

Örnek:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

Bu seçenek, herhangi bir tip hatası tespit edilirse derleyicinin JavaScript dosyaları yaymasını engeller. Bu, yalnızca geçerli kodun oluşturulmasını sağlar.

Örnek:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

Bu seçenek, tüm katı tip kontrolü seçeneklerini etkinleştirir. Bu, potansiyel hataları yakalamaya ve en iyi uygulamaları uygulamaya yardımcı olduğundan, yeni projeler için şiddetle tavsiye edilir.

Örnek:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

Katı modu etkinleştirmek, aşağıdaki seçenekleri etkinleştirmeye eşdeğerdir:

• noImplicitAny
• noImplicitThis
• alwaysStrict
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• noImplicitReturns
• noFallthroughCasesInSwitch

esModuleInterop

Bu seçenek, CommonJS ve ES modülleri arasında birlikte çalışabilirliği etkinleştirir. CommonJS modüllerini ES modüllerinde ve tersini içe aktarmanıza izin verir.

Örnek:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

Bu seçenek, dosya adlarında tutarlı büyük/küçük harf kullanımını zorlar. Bu, bazı işletim sistemlerinin büyük/küçük harfe duyarlı olması ve bazılarının olmaması nedeniyle platformlar arası uyumluluk için önemlidir.

Örnek:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl ve paths

Bu seçenekler, modül çözümlemesini yapılandırmanıza olanak tanır. baseUrl, göreli olmayan modül adlarını çözümlemek için temel dizini belirtir ve paths özel modül takma adları tanımlamanıza olanak tanır.

Örnek:

            "compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@components/*": ["src/components/*"],
    "@utils/*": ["src/utils/*"]
  }
}
            

              
                Copy
              
            
          

Bu yapılandırma, @components/MyComponent ve @utils/myFunction gibi takma adlar kullanarak modülleri içe aktarmanıza olanak tanır.

Gelişmiş Yapılandırma: Temellerin Ötesinde

Şimdi, TypeScript geliştirme deneyiminizi daha da geliştirebilecek bazı gelişmiş tsconfig.json seçeneklerini inceleyelim.

Artımlı Derleme

TypeScript, büyük projeler için derleme sürecini önemli ölçüde hızlandırabilen artımlı derlemeyi destekler. Artımlı derlemeyi etkinleştirmek için, incremental seçeneğini true olarak ayarlayın ve bir tsBuildInfoFile seçeneği belirtin.

Örnek:

            "compilerOptions": {
  "incremental": true,
  "tsBuildInfoFile": ".tsbuildinfo"
}
            

              
                Copy
              
            
          

tsBuildInfoFile seçeneği, derleyicinin derleme bilgilerini saklayacağı dosyayı belirtir. Bu bilgi, sonraki derlemeler sırasında hangi dosyaların yeniden derlenmesi gerektiğini belirlemek için kullanılır.

Proje Referansları

Proje referansları, kodunuzu daha küçük, daha yönetilebilir projelere yapılandırmanıza olanak tanır. Bu, büyük kod tabanları için derleme sürelerini ve kod organizasyonunu iyileştirebilir. Bu konsepte iyi bir benzetme, bir Mikro hizmet mimarisidir - her hizmet bağımsızdır, ancak ekosistemdeki diğerlerine bağlıdır.

Proje referanslarını kullanmak için, her proje için ayrı bir tsconfig.json dosyası oluşturmanız gerekir. Daha sonra, ana tsconfig.json dosyasında, references seçeneğini kullanarak başvurulması gereken projeleri belirtebilirsiniz.

Örnek:

            {
  "compilerOptions": {
    ...
  },
  "references": [
    { "path": "./project1" },
    { "path": "./project2" }
  ]
}
            

              
                Copy
              
            
          

Bu yapılandırma, geçerli projenin ./project1 ve ./project2 dizinlerinde bulunan projelere bağlı olduğunu belirtir.

Özel Dönüştürücüler

Özel dönüştürücüler, TypeScript derleyicisinin çıktısını değiştirmenize olanak tanır. Bu, özel kod dönüşümleri eklemek, kullanılmayan kodu kaldırmak veya belirli ortamlar için çıktıyı optimize etmek gibi çeşitli amaçlar için kullanılabilir. Genellikle i18n uluslararasılaştırma ve yerelleştirme görevleri için kullanılırlar.

Özel dönüştürücüleri kullanmak için, derleyici tarafından çağrılacak bir işlevi dışa aktaran ayrı bir JavaScript dosyası oluşturmanız gerekir. Daha sonra, tsconfig.json dosyasındaki plugins seçeneğini kullanarak dönüştürücü dosyasını belirleyebilirsiniz.

Örnek:

            {
  "compilerOptions": {
    ...
    "plugins": [
      { "transform": "./transformer.js" }
    ]
  }
}
            

              
                Copy
              
            
          

Bu yapılandırma, ./transformer.js dosyasının özel bir dönüştürücü olarak kullanılması gerektiğini belirtir.

Dosyalar, Dahil Etme ve Hariç Tutma

compilerOptions'ın ötesinde, tsconfig.json'daki diğer kök düzey seçenekler, derleme sürecine hangi dosyaların dahil edildiğini kontrol eder:

• files: Derlemeye dahil edilecek dosya yollarının dizisi.
• include: Dahil edilecek dosyaları belirten glob desenlerinin dizisi.
• exclude: Hariç tutulacak dosyaları belirten glob desenlerinin dizisi.

Bu seçenekler, TypeScript derleyicisi tarafından hangi dosyaların işlendiği konusunda ayrıntılı kontrol sağlar. Örneğin, derleme işleminden test dosyalarını veya oluşturulan kodu hariç tutabilirsiniz.

Örnek:

            {
  "compilerOptions": { ... },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

Bu yapılandırma, src dizinindeki ve alt dizinlerindeki tüm dosyaları dahil ederken, node_modules ve dist dizinlerindeki dosyaları ve .spec.ts uzantısına sahip (genellikle birim testleri için kullanılan) herhangi bir dosyayı hariç tutar.

Belirli Senaryolar İçin Derleyici Seçenekleri

Farklı projeler, optimum sonuçlar elde etmek için farklı derleyici ayarları gerektirebilir. Şimdi, birkaç özel senaryoya ve her biri için önerilen derleyici ayarlarına bakalım.

Web Uygulaması Geliştirme

Web uygulaması geliştirme için, genellikle aşağıdaki derleyici ayarlarını kullanmak istersiniz:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

Bu ayarlar, React veya diğer benzer çerçeveleri kullanan modern web uygulamaları için uygundur. En son ECMAScript özelliklerini hedefler, ES modüllerini kullanır ve katı tip kontrolünü etkinleştirirler.

Node.js Arka Uç Geliştirme

Node.js arka uç geliştirmesi için, genellikle aşağıdaki derleyici ayarlarını kullanmak istersiniz:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "sourceMap": true,
    "outDir": "dist",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

Bu ayarlar, CommonJS modül sistemini kullanan Node.js uygulamaları için uygundur. En son ECMAScript özelliklerini hedefler, katı tip kontrolünü etkinleştirir ve JSON dosyalarını modül olarak içe aktarmanıza izin verir.

Kitaplık Geliştirme

Kitaplık geliştirme için, genellikle aşağıdaki derleyici ayarlarını kullanmak istersiniz:

            {
  "compilerOptions": {
    "target": "ES5",
    "module": "UMD",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

Bu ayarlar, hem tarayıcı hem de Node.js ortamlarında kullanılabilen kitaplıklar oluşturmak için uygundur. Geliştirici deneyimini iyileştirmek için bildirim dosyaları ve kaynak haritaları oluştururlar.

TSConfig Yönetimi İçin En İyi Uygulamalar

tsconfig.json dosyalarınızı yönetirken aklınızda bulundurmanız gereken bazı en iyi uygulamalar şunlardır:

• Temel bir yapılandırmayla başlayın: Ortak ayarlara sahip temel bir tsconfig.json dosyası oluşturun ve ardından extends seçeneğini kullanarak diğer projelerde genişletin.
• Katı modu kullanın: Potansiyel hataları yakalamak ve en iyi uygulamaları uygulamak için katı modu etkinleştirin.
• Modül çözümlemesini yapılandırın: İçe aktarma hatalarını önlemek için modül çözümlemesini düzgün bir şekilde yapılandırın.
• Proje referanslarını kullanın: Kodunuzu proje referanslarını kullanarak daha küçük, daha yönetilebilir projelere yapılandırın.
• tsconfig.json dosyanızı güncel tutun: tsconfig.json dosyanızı düzenli olarak gözden geçirin ve projeniz geliştikçe güncelleyin.
• tsconfig.json dosyanızı sürüm kontrolü yapın: tsconfig.json dosyanızı diğer kaynak kodunuzla birlikte sürüm kontrolüne kaydedin.
• Yapılandırmanızı belgeleyin: Her seçeneğin amacını açıklamak için tsconfig.json dosyanıza yorumlar ekleyin.

Sonuç: TypeScript Yapılandırmasında Uzmanlaşmak

tsconfig.json dosyası, TypeScript derleyicisini yapılandırmak ve derleme sürecini kontrol etmek için güçlü bir araçtır. Mevcut seçenekleri anlayarak ve en iyi uygulamaları izleyerek, TypeScript projelerinizi optimum performans, sürdürülebilirlik ve uyumluluk için ince ayar yapabilirsiniz. Bu rehber, tsconfig.json dosyasında bulunan gelişmiş seçeneklerin kapsamlı bir genel bakışını sunarak, TypeScript geliştirme iş akışınızın tam kontrolünü elinize almanızı sağlar. En güncel bilgiler ve rehberlik için her zaman resmi TypeScript belgelerine başvurun. Projeleriniz geliştikçe, bu güçlü yapılandırma araçlarını anlama ve kullanma biçiminiz de gelişmelidir. İyi kodlamalar!